Reverse Code Engineering RCE CD +sandman 2000

home *** CD-ROM | disk | FTP | other *** search

/ Reverse Code Engineering RCE CD +sandman 2000 / ReverseCodeEngineeringRceCdsandman2000.iso / RCE / Softice Tuts / si-ug-chapter05.rtf < prev next >

Wrap

Text File | 2000-05-25 | 70.9 KB | 2,204 lines

CHAPTER 5 - Using Other Commands 05.01 Display and Edit Commands 05.02 I/O Port Commands 05.03 Transfer Control Commands 05.04 Debug Mode Commands 05.05 Utility Commands 05.06 Specialized Debugging Commands 05.07 Windowing Commands 05.08 Debugger Customization Commands 05.09 Screen Control Commands 05.10 Symbol and Source Line Commands 05.01 Display and Edit Commands U Unassemble instructions or display source R Display or change registers MAP Display system memory map D, DB, DW, DD Display memory E, EB, EW, ED Edit memory INT? Display last interrupt number ? or H Display help information VER Display Soft-ICE version number Unassemble instructions or display source Syntax : U [address] [L[=]length] Length : The number of instructions to be unassembled Comments : The U command displays the instructions of the program being debugged. If length is not specified, the length defaults to eight lines if available, or one less than the screen length. If address is not specified, the command unassembles at address starting at the first byte after the last byte unassembled by a previous unassemble command. If the has been no previous unassemble command, the address defaults to the current CS:IP. If the code window is visible, the instructions are displayed in the code window. If source is loaded for the address range specified then source lines may be displayed depending on the current source mode. Example : U $-10 This command unassembles instructions beginning 10 hexadecimal bytes before the current address. U .499 This command displays the current source file starting at line 499. The code window must be visible and in source mode. Display or change registers Syntax : R register-name [ [ = ]value] ] Register-name : Any register (FL for flags) Value : If register-name is any name other than FL, value is a hex value or an expression. If register-name is FL, value is a series of one or more of the following flag symbols, each optionally preceded by a plus or minus sign : O (Overflow flag), D (Direction flag), I (Interrupt flag), S (Sign flag), Z (Zero flag), A (Auxiliary carry flag), P (Parity flag), C (Carry flag). Comments : The R command displays or changes register values. If no parameters are supplied, all register and flag value are displayed, as well as the instruction at the current CS:IP address. If register-name is supplied without a value, Soft-ICE displays the current value of the specified register and prompts you for a new value. If register-name is FL, flags that are set are displayed as highlighted uppercase characters; flags that are cleared are displayed as non-highlighted lowercase characters. To retain the current value of a register, press ENTER. If both register-name and value are supplied, the specified register's contents are changed to the value. To change a flag value, use FL as the register-name, followed by the symbols of the flag whose values you want to toggle. To turn a flag on, precede the flag symbol with a plus sign. To turn a flag off, precede the flag symbol with a minus sign. The flags can be listed in any order. Examples : RAH 5 This command sets the AH register equal to 5. R FL = OZP This command toggles the O, Z, and P flag values. R FL This command displays the current flag values, and allows them to be changed. RFL O + A-C This command toggles the O flag value, turns on the flag value, and turns off the C flag value. Display system memory map Syntax : MAP Comments : The MAP command displays the names, locations, and sizes of system memory components. The size is displayed in paragraphs. One paragraph is equivalent to 10 hexadecimal bytes. The component that the CS:IP register currently points to is highlighted. Use the MAP command when A break point occurs and CS:IP is not in a known memory region. You want to get control within a resident program or system program. A range break point can be set based on the starting address and size reflected by MAP. You suspect a program or system component of writing over code outside of its memory space. MAP is used to obtain the memory address of the region to use with the CSIP command. You need to find out which resident program owns certain interrupt vectors. Example : MAP The following is a sample display produced by the command : Start Length 0000:0000 0040 Interrupt Vector Table 0040:0000 0030 ROM BIOS Variables 0070:0000 00FE I/O System 016E:0000 06B7 DOS 0842:0000 02CE DOS File Table & Buffers A000:0000 5E00 System BUS F000:0000 1000 ROM BIOS Versions of DOS lower than 3.1 display program addresses instead of displaying the program names. Display memory Syntax : D [size] [address] [L[ = ]length] Size : B(yte), W(ord), D(ouble) Length : The number of bytes to be displayed. Comments : The D command displays the memory contents of the specified address. The contents are displayed in the format of the size specified. If no size is specified, the last size used will be displayed. The ASCII representation is also displayed for all forms. If address is not specified, the command displays memory at the address starting at the first byte after the last byte displayed. If length is not specified, it defaults to eight lines, or fewer if the window is smaller. If the data window is visible, the data is displayed in the data window and the length is ignored. Example : DW DS:00 L=8 This command displays, in word format and in ASCII format, the value of the first eight bytes of the current data segment. Edit memory Syntax : D [size] [address] [L[ = ]length] Size : B(yte), W(ord), D(ouble) Data-list : list of data objects of the specified size (Bytes, Words or Double Words) or quoted strings separated by commas or spaces. The quoted string can begin with a single quote or a double quote. Comments : The E commands display the memory contents at the specified address, and allow you to edit the values. These commands display the memory contents in ASCII format, and in the format of the size specified. A memory editor is provided for quick memory updates. Memory can be edited by typing ASCII characters, or by typing byte, word, or double word values. If no size is specified, the last size used will be assumed. The memory Editing key strokes are: UP Move cursor up DOWN Move cursor down LEFT Move cursor right RIGHT Move cursor left SPACE Move cursor to next element TAB Toggle between numeric and ASCII areas ESC or ENTER Exit memory editor As values are input, the actual memory locations are updated. All numeric values are hex numbers. To toggle between the ASCII and numeric display areas, press the TAB key. If the data window is visible, the data is edited in the data window, otherwise the data is edited in the command window. The data display length defaults to 8 lines if in the command window, or to the size of the data window if it's visible. If no parameters are supplied, the cursor moves into the data window if the data window if visible. If the data window is not visible, the data is edited in the command window at the last address displayed or edited. Examples : EB 1000:0 This command displays, in byte format, up to six lines containing both the numeric and the ASCII representation of the values of the data starting at location 1000:0000. Once the lines are displayed, you can edit the values. EB 8000:0 "Hello",0D This command replaces the values starting at location 8000:0000 with the string "Hello" followed by a carriage return. Display last interrupt number Syntax : INT? Comments : The INT? command displays the address and the number the last interrupt that happened. Example : INT? An example of the display produced by the INT? command follows: Last Interrupt: 16 At: 0070:0255 This example shows that the last interrupt generated in the system before the Soft-ICE window was brought up was an interrupt 16 hexadecimal, at location 0070:0255H. If the last interrupt that happened was a software interrupt, unassembling the code at 0070:0255H will show the interrupt instruction. If it was a hardware interrupt, unassembling the code will show the instruction that was executing when the hardware interrupt occurred. Display help information Syntax : < ? | H > [command | expression] Comments : The ? command and the H command both display help information. If no parameters are specified, help displays short descriptions of all the commands and operators, one screen at a time. Press any key to continue, or press ESC to quit displaying help. If command is specified, help displays more detailed information on the specified command, including the command syntax and an example. If expression is specified, the expression is evaluated and the result is displayed in hexadecimal, decimal, and ASCII. Examples : ? ALTKEY This command displays information about the ALTKEY command, including its syntax and an example. H 10 + 14*2 This command displays: 0038 00056 "8". These are the hexadecimal, decimal and ASCII representations of value of the expression "10 + 14*2". Display Soft-ICE version number Syntax : VER Example : VER This command displays the Soft-ICE version and the Nu-Mega Technologies copyright message. 05.02 I/O Port Commands I, IB or IW Input from I/O port O, OB or OW Output to byte I/O port Input from I/O port Syntax : I [size] port Size : B(yte), W(ord), D(ouble) Port : A byte or word value Comments : The input from port commands are used to read and display a value from a hardware port. Input can be done From byte or word ports. If no size is specified, the default is byte. Example : I 21 This command displays the mask register for interrupt controller one. Output from I/O port Syntax : O [size] port Size : B(yte), W(ord), D(ouble) Port : A byte or word value Value : A byte for a byte port or a word for a word port Comments : The output to port commands are used to write a value to a hardware port. Output can be done to byte or word ports If no size is specified, the default is byte. Example : O 21 FF This command masks off all the interrupts for interrupt controller one. 05.03 Transfer Control Commands X Exit from Soft-ICE window G Go to address T Trace one instruction P Program step HERE Go to current cursor line GENINT Force an interrupt EXIT Force exit of current DOS program BOOT System boot (retain Soft-ICE) HBOOT Hard system boot (total reset) Exit from Soft-ICE window Syntax : X Comments : The X command exits the Soft-ICE window and restores control to the program that was interrupted to bring up Soft-ICE. The Soft-ICE window disappears. If any break points have been set, they become active. Example : X Exits the Soft-ICE window and restores control to the program that was interrupted. Go to address Syntax : G [=start-address] [break-address] Comments : The G command exits from the Soft-ICE window with a single one-time execution break point set. In addition, all sticky break points are armed. Execution begins at the current CS:IP unless the start-address parameter is supplied. In that case execution begins at start-address. Execution continues until break-address is encountered, the window pop-up key sequence is used, or a sticky break point occurs. The break-address must be the first byte of an instruction opcode. When the specified break-address is reached, the current CS:IP will be the instruction where the break point was set. The G command with no parameters behaves the same as the X command. The non-sticky execution break point uses an 80386 break point register, unless all break point registers have been allocated to sticky break points. In that case, an INT 3 style break point is implemented. When this case occurs, the G and P commands will not work correctly in ROM. An error message will be displayed if this is attempted. Example : G CS:1234 This command sets a one time break point at CS:1234 Trace one instruction Syntax : T [=start-address] [count] Comments : The T command single steps one instruction by utilizing the single step flag. Execution begins at the current CS:IP unless the start-address parameter is specified. If start-address is specified, CS:IP is changed to start- address prior to single stepping. If count is specified then Soft-ICE single steps count time The TRACE command will continue until the count is exhausted or the Esc key is pressed, regardless of which break points are reached. In source mode, the T command steps to the next source statement. If the current statement is a procedure or function call, and source exists for the routine being called, T steps into the call. If there is no source available for the called procedure or function, T steps over the routine. Example : T = 1284 3 This command single steps through three instruction starting at memory location 1284. Program step Syntax : P Comments : The P command is a logical program step. One instruction at the current CS:IP is executed unless the instruction is a call, interrupt, loop, or repeated string instruction. In those cases, the entire routine or iteration is completed before control is returned to Soft-ICE. The P command uses a one-time execution break point. The non-sticky execution break point uses an 80386 break point register, unless all break point registers have been allocated to sticky break points. In that case, an INT3 style break point is implemented. When this case occurs, the P and G commands will not work correctly in ROM. An error message will be displayed if this is attempted. In source mode, the P command steps to the next source statement. If the current statement is a procedure or function call, the P command steps over the it. Example : P This command executes one 'program step'. Go to current cursor line Syntax : HERE Comments : The HERE command executes until the program reaches the current cursor line. HERE is only available when the cursor is in the code window. If the code window is not visible or the cursor is not in the code window, use the G command instead. The HERE command exits from Soft-ICE with a single one-time execution break point set. In addition, all sticky break points are armed. Execution begins at the current CS:IP and continues until address of the current cursor position in the code window encountered, the window pop-up key sequence is used, a sticky break point occurs. The non-sticky execution break point uses an 80386 break point register, unless all break point registers have been allocated to sticky break points. In that case, an INT 3 style break point is implemented. When this case occurs, the HERE command will not work correctly in ROM. An error message will be displayed if this is attempted. Example : HERE This example sets an execution break point at the current cursor position, then exits from Soft-ICE and begins execution at the current CS:IP. Default Function Key: F7 Force an interrupt Syntax : GENINT INT1 | INT3 | NMI | interrupt-number Interrupt-number : a number in the range 00 - FF Comments : The GENINT command forces an interrupt to occur. This function can be used to hand off control to another debugger when using Soft-ICE with another software debugger. It can also be used to test interrupt routines. The GENINT command simulates the processing sequence of a hardware interrupt or an INT instruction. It pushes the flags, the CS register, and the IP register, then changes the value of the CS and IP registers to the value of the interrupt vector table entry corresponding with the specified interrupt number. Example : GENINT NMI This forces a non-maskable interrupt. This will give control back to CodeView if Soft-ICE is being used as an assistant to CodeView. Force exit of current DOS program Syntax : EXIT [R] [D] R : Restore the interrupt vector table D : Delete all break points Comments : The EXIT command attempts to abort the current program by forcing a DOS exit function (INT 21H, function 4CH) This command will only work if the DOS is in a state where it is able to accept the exit function call. If this call is made from certain interrupt routines, or other times when the DOS is not ready, the system may behave unpredictably. This function does NOT do any system resetting other than the interrupt table when the R option is used. This means that BIOS variables, video modes and other systems level data are not restored. Using the R option will cause the interrupt vectors to be restored to whatever they were the last time they were saved. Soft-ICE saves the interrupt vectors when it is loaded, when a program is loaded with LDR.EXE, and when the VECS S command is used. Note : To re-start a program that has been loaded with the Soft-ICE program loader (LDR.EXE) do the following: EXIT R LDR prog.EXE The EXIT command will restore the interrupt table to the values it contained before the program was loaded, then exit to the command processor. By running the LDR utility and specifying the .EXE suffix, the program is loaded back in without re-loading symbols and source. The symbols and source will remain in memory. Caution : The EXIT command should be used with care. Since Soft-ICE can be popped up at any time, a situation can occur where the DOS is not in a state to accept an exit function call. Also, the EXIT command does not do any program specific resetting. For instance, the EXIT command does not reset the video mode. If your program has placed the video BIOS and hardware in a particular video mode, it will stay in that mode after the EXIT command. Example : EXIT R Restores the interrupt table and exits the current program. The R option should be used if exiting from a program loaded with the Soft-ICE program loader LDR.EXE. System boot (retain Soft-ICE) Syntax : BOOT Comments : The BOOT command resets the system and retains Soft-ICE. BOOT is required to debug boot sequences, DOS loadable drivers, and non-DOS operating systems. BOOT is implemented with an Interrupt 19H ROM BIOS call. In some instances memory may be corrupted to the point where Interrupt 19 will not work. If this occurs, bring up Soft-ICE and use the HBOOT command. For BOOT to work properly, Soft-ICE should be installed as a loadable driver in CONFIG.SYS before any other device drivers. This is so Soft-ICE can restore the original system state as accurately as possible. Example : BOOT This command makes the system reboot. Soft-ICE remains resident. Hard system boot (total reset) Syntax : HBOOT Comments : The HBOOT command resets the entire system. Soft-ICE is not retained in the reset process. HBOOT is sufficient unless an adapter card requires a power-on reset. In those rare cases, the machine power must be recycled. Example : HBOOT This command makes the system reboot. Soft-ICE must be reloaded. 05.04 Debug Mode Commands ACTION Set action after break point is reached WARN Set DOS/ROM BIOS re-entrancy warning mode BREAK Break out any time I3HERE Direct Interrupt 3's to Soft-ICE Set action after break point is reached Syntax : ACTION [INT1 | INT3 | NMI | HERE | int-number] Int-number : Any valid interrupt number (0-FFH). Use this option only if a user-supplied break point qualification routine has taken over that interrupt vector (see section 11.2). Comments : The ACTION command determines where control is given when break point conditions have been met. In most cases, the desired action is INT3 or HERE, INT3 is typically used if Soft-ICE is being used with a host debugger, HERE is used when it is desired to return to Soft-ICE when break point conditions have been met, INT1 and NMI are alternatives for certain debuggers that will not work with the INT3 option. For instance, CODEVIEW works best with ACTION set to NMI. Use int-number if there is a user-supplied break point qualification routine installed. Using int-number without having a user-supplied break point qualification routine installed causes an error. For more information, see section 11.2,'User-Qualified Break Points'. If no parameter is supplied with the ACTION command, the current action is displayed. The default action is HERE. Example : ACTION HERE This command specifies that control will return to Soft-ICE when break point conditions have been met. Set DOS/ROM BIOS re-entrancy warning mode Syntax : WARN [ON | OFF] Comments : The WARN command is provided for using Soft-ICE with debuggers that use DOS and ROM BIOS. Many debuggers use DOS and ROM BIOS for screen output and for receiving keystrokes. Since DOS and ROM BIOS are not fully re- entrant, these debuggers may not work properly if break point occurs while the DOS or ROM BIOS is executing. If WARN ON is set, and ACTION is not HERE, then control will come to Soft- ICE before the actual action occurs. The system displays the current CS:IP and gives you the choice of continuing or returning to Soft-ICE. Generally, you should choose to return to Soft-ICE to continue your debugging. Only continue with the host debugger if you know your debugger will not cause DOS or ROM BIOS to be re-entered. WARN mode should be turned on to use Soft-ICE with DEBUG, SYMDEB, and CODEVIEW. If no parameter is specified, the current state of WARN is displayed. The default is WARN mode OFF. Example : WARN ON This command turns on DOS/ROM BIOS re-entrancy warning mode. Break out any time Syntax : BREAK [ON | OFF] Comments : The BREAK command allows popping up the Soft-ICE window when the system is hung with interrupts disabled. Break mode can be used for the entire debugging session, or it can be turned on and off when it is required. Break mode degrades system performance slightly. This performance degradation must be weighed against the necessity of breaking out of a hung program. A user may want to have break mode on all the time, even though performance is degraded, because the program could hang at any time. Unlike other debuggers that can also be brought up at any time, Soft-ICE does not require an external switch. When BREAK is on, the Soft-ICE window can be brought up at any time by pressing the current key sequence. If no parameter is specified, the current state of BREAK is displayed The default is BREAK mode OFF. Example : BREAK ON This command turns on break mode. This means that the Soft-ICE window can be brought up at any time, even if interrupts are disabled. Direct Interrupt 3's to Soft-ICE Syntax : I3HERE [ON | OFF] Comments : The I3HERE command lets you specify that any Interrupt 3 will bring up the Soft-ICE window. This feature is useful for stopping your program in a specific location. To use this feature, place an INT 3 into your code at the location where you want to stop. When the INT 3 occurs, it will bring up the Soft-ICE window. At this point, you can use the R IP command to change your instruction pointer to the instruction after the INT 3, then you can continue debugging. If no parameter is specified, the current state of 13HERE is displayed. The default is 13HERE mode OFF. Example : I3HERE ON This command turns on 13HERE mode. Any INT 3's generated after this point will bring up the Soft-ICE window. 05.05 Utility Commands A Assemble code S Search for data F Fill memory with data M Move data C Compare two data blocks Assemble code Syntax : A [address] Comments : The Soft-ICE assembler allows you to assemble instructions directly into memory. The assembler supports the basic 8086 instruction set with the 80186 and 80286 real address mode extensions. Numeric co-processor instructions and 80386 specific instructions, registers and addressing modes can NOT be assembled. The A command enters the Soft-ICE interactive assembler. An address is displayed as a prompt for each assembly line After an assembly language instruction is typed in and ENTER is pressed, the instructions are assembled into memory at the specified address. Instructions must be entered with standard Intel format. Press ENTER at an address prompt to exit assembler mode. If the address range in which you are assembling instructions is visible in the code window, the instructions will change interactively as you assemble. The Soft-ICE assembler supports the standard 8086 family mnemonics, however there are some special additions : The DB mnemonic is used to define bytes of data directly into memory. The DB command is followed by a list of bytes and/or quoted strings separated by spaces or commas. The RETF mnemonic represents a far return. WORD PTR and BYTE PTR are used to determine data size if there is no register argument, for example: MOV BYTE PTR ES:[ 1234],1. Use FAR and NEAR to explicitly assemble far and near jumps and calls. If FAR or NEAR is not specified then all jumps and calls are near. Operands referring to memory locations should placed in square brackets, for example: MOV AX,[1234]. Example : A CS:1234 This command prompts you for assembly instruction then assembles them beginning at offset 1234H with the current code segment. Press ENTER at the address prompt after entering the last instruction. Search for data Syntax : S address L length data-list Data-list : list of bytes or quoted strings separated by commas or spaces. A quoted string can begin with a single quote or a double quote. Length : length in bytes Comments : The S command searches memory for a series of bytes or characters that matches the data-list. The search begins at the specified address and continues for the length specified. The address of each occurrence found in the range is displayed. Example : S DS:SI+10 L CX 'Hello',12,34 This command searches for the string 'Hello' followed by the bytes 12H and 34H starting at offset SI+10 in the current data segment and ending CX bytes later. Fill memory with data Syntax : F address L length data-list Data-list : list of bytes or quoted strings separated by commas or spaces. A quoted string can begin with a single quote or a double quote. Length : length in bytes Comments : The F command fills memory with the series of bytes or characters specified in the data-list. Memory is filled starting at the specified address and continuing for the specified length, repeating the data-list if necessary. Example : F 8000:0 L 100 'Test' This command fills memory starting at 8000:0 for a length of 100H bytes with the string 'Test'. The string Test' is repeated until the fill length is exhausted. Move data Syntax : M start-address L length end-address Length : length in bytes Comments : The M command moves the specified number of bytes from the start-address in memory to the end-address in memory. Example : M 1000:0 L 200 2000:0 This command moves 200H bytes from memory location 1000:0 to memory location 2000:0. Compare two data blocks Syntax : C address1 L length address2 Length : length in bytes Comments : The C command compares the memory block specified by address1 and the length with the memory block specified address2 and the length. When a byte from the first data block does not match a byte from the second data block, both bytes are displayed, along with their addresses. Example : C 5000:100 L 10 6000:100 This command compares the 10H bytes starting at memory location 5000:100 with the 10H bytes starting at memory location 6000:100. 05.06 Specialized Debugging Commands SHOW Display instructions from history buffer TRACE Enter trace simulation mode XT Single step in trace simulation mode XP Program step in trace simulation mode XG Go to address in trace simulation mode XRSET Reset back trace buffer VECS Save/restore/compare interrupt vectors SNAP Take snap shot of memory block EMMMAP Display EMM allocation map Display instructions from history buffer Syntax : SHOW [B | start] B : This tells the show command to start the display with the oldest instruction in the back trace buffer. start : The number of instructions back from the buffer end (last instruction captured) to begin display. Comments : The SHOW command displays instructions from the back trace history buffer. If source is available for the instructions then the display is in mixed mode, otherwise only code is displayed. SHOW allows scrolling through the back trace buffer with the up, down, Pageup and PaqeDn keys. To exit from SHOW you must press the Esc key. Preceding the address of each instruction is the buffer entry number. This number shows how deep into the buffer you are displaying. The higher the number, the deeper you are into the buffer. Note : Before using the SHOW command, instructions must have been logged with a back trace range. See chapter 9 for more information on back trace ranges. Hints : It is often useful to have the code window visible with the actual code of the region you are displaying from the back trace buffer. When you compare the actual instruction flow to code, displayed jumps and calls are usually less confusing. Using SHOW in conjunction with the TRACE command will allow you to see the instructions in the back trace history buffer from two different points of view. Example : SHOW 40 This example will displays starting with the 40th instruction back in the back trace buffer. Enter trace simulation mode Syntax : TRACE [start] | [OFF] start : The number of instructions back from the buffer end (last instruction captured) to begin trace simulation. OFF : Exit trace simulation mode. Comments : The TRACE command allows you to replay instructions from the instruction back trace history buffer just as if they were being executed for the first time. To use trace simulation mode you must have the code window visible After entering trace simulation mode you use the XT, XP and XG commands to trace through the instructions in the buffer. To exit trace simulation mode type TRACE OFF. TRACE with no parameters specified displays whether trace simulation mode is on or off. Note : Before using the TRACE command, instructions must have been logged with a back trace range. See chapter 9 for more information on back trace ranges. Hints : Trace simulation mode is most useful when the code window is visible. It is often useful to use TRACE in conjunction with the SHOW command. This allows the instructions in the back trace history buffer to be viewed simultaneously in two different forms. Example : TRACE 40 This example enters trace simulation mode starting 40 instructions back from the last instruction logged. It will remain in trace simulation mode until TRACE OFF is entered. Single step in trace simulation mode Syntax : XT [R] R : Single step in reverse direction. Comments : The XT command single steps through the instruction back trace history buffer. This command acts like the T command for normal debugging. Note that the registers do NOT change while stepping in trace simulation mode except CS and IP. The XT instruction allows you to replay instructions from the back trace history buffer, Note : Before using XT you must be in trace simulation mode. See chapter 9 and the TRACE command in this section for more information on back trace ranges. Hint : If you are using XT frequently, like any other Soft-ICE command it can be assigned to a function key. Example : XT This command single steps one instruction in trace simulation mode. Program step in trace simulation mode Syntax : XP Comments : The XP command does a logical program step through the instruction back trace history buffer. This command acts like the P command for normal debugging. Note that the registers do NOT change while stepping in trace simulation mode except CS and IP. The XP instruction allows you to replay instructions from the back trace history buffer. Note : Before using XP you must be in trace simulation mode. See chapter 9 and the TRACE command in this section for more information on back trace ranges. Hint : If you are using XP frequently, like any other Soft-ICE command it can be assigned to a function key. Example : XP This command executes one program step in trace simulation mode. Go to an address in trace simulation mode Syntax : XG [R] address R : Search for address in reverse direction. Address : Address to go to in the back trace history buffer. Comments : The XG command moves the instruction pointer to the next occurrence of the specified address in the back trace history buffer. If R is specified preceding the address, then the instruction pointer is moved to the previous occurrence the specified address in the back trace buffer. The address must be the first byte of an instruction opcode. The XG is analogous to the G command in normal debugging. Note : Before using XG you must be in trace simulation mode. See chapter 9 and the TRACE command in this section for more information on back trace ranges. Example : XG 273:1030 This command moves the instruction pointer to the next instance of the instruction at address 273:1030. Reset back trace history buffer Syntax : XRSET Comments : The XRSET command resets the back trace history buffer. This command should be executed before setting a back trace range if there is unwanted instruction information in the back trace buffer. Example : XRSET This command resets the back trace buffer. Save/restore/compare interrupt vectors Syntax : VECS [C|S|R] C : Compare current table with stored table S : Save current interrupt table to buffer R : Restore interrupt table from buffer Comments : The VECS command allows you to save and restore the interrupt table to an internal Soft-ICE buffer. The actual table can also be compared to the stored table with the differences displayed. When the C option is used to compare the current interrupt vector table with the stored copy the output is in the following format: address old-vector new-vector Each vector that has changed is displayed. The interrupt vector table is initially stored when Soft-ICE is loaded. It is also automatically stored when a program loaded with LDR.EXE. Only one copy of the interrupt vector table is stored, so each time VECS S is executed, previous copy of the interrupt table is overwritten. If no parameters are specified, the entire interrupt vector table is displayed. Example : VECS C This command compares the actual interrupt vector table with one that had been previously stored in the Soft-ICE internal VECS buffer. Take snap shot of memory block Syntax : SNAP [C | S | R] address1 address2 C : Compare buffer with address range S : Save address range to buffer R : Restore buffer to address range Comments : The SNAP command takes a snap shot of a memory block for later comparison. The S option copies a block of memory to a buffer in extended memory. The C option displays differences between the buffer in extended memory and the actual memory specified by the address range. The R option copies the buffer in extended memory to the address range in conventional memory. When the C option is used to compare the buffer with the address range the output is in the following format : address old-data new-data Each byte that has changed is displayed. The address is usually not necessary for the C and R options. If the address is not specified, the address from the last time SNAP was entered with a specified address used. Notes : To use the SNAP command you must have specified the /TRA XXXX switch on the S-ICE.EXE line in CONFIG.SYS. The SNAP command saves data in the back trace history buffer. If you are using back trace then you will have a conflict with SNAP. Specifically, SNAP will overwrite back trace information if you do a SNAP S when instruction history is in the back trace buffer. Conversely, if you have saved a region with SNAP, then enabling a back trace range will overwrite the SNAP buffer. Example : SNAP S 2000:0 4000:0 This command stores the data block from 2000:0 to 4000:0 in the Soft-ICE back trace buffer. Display EMM allocation map Syntax : EMMMAP Comments : The EMMMAP command displays each physical page that is available for EMM memory and the pages that are currently mapped in. Note : The Soft-ICE EMM feature must be enabled to use this function. See chapter 8 for more information on enabling EMM capability. Example : EMMMAP This example displays the current EMM allocation in in the following form. Phy page Seg address Handle/Page 00 D000 FFFF 01 D400 0001/0000 02 D800 0001/0001 03 DC00 0001/0002 In this example, physical page 0 is located at D000 and is unmapped. Physical page 1 is located at D400 and has handle 1, page 0 mapped into it. Physical page 2 is located at D800 and has handle 1, page I mapped into it. Physical page 3 is located at DC00 and has handle page 2 mapped into it. 05.07 Windowing Commands WR Toggle register window WC Toggle/set size of code window WD Toggle/set size of data window EC Enter/exit code window . Locate current instruction Three window types may be created with Soft-ICE: register, data, and code. Any of these windows can be toggled on or off at any time. The data and code windows can be of variable size; the register window is fixed in size. The windows always remain in a fixed order. Starting from the top of the screen, the order is register window, data window, then code window. Toggle register window Syntax : WR Comments : The command makes the register window visible if not currently visible. If the register window is currently visible, WR removes the register window. The register window displays the 8086 register set and the processor flags. Default Function: F2 Toggle/set size of code window Syntax : WC [window-size] Window-size : a decimal number between one and 21. Comments : If window-size is not specified, this command toggles the code window. If it was not visible it is made visible, and if it was visible it is removed. If window-size is specified the code window is resized, or it was not visible it is made visible with the specified size. Note : If you wish to move the cursor to the code window use the EC command. See description of the EC command for more details. Example : WC 12 If no code window is present, then a code window 12 lines in length is created. If the code window is currently on the screen, it is resized to 12 lines. Toggle/set size of data window Syntax : WD [window-size] Window-size : a decimal number between one and 21. Comments : If window-size is not specified, this command toggles the data window. If it was not visible it is made visible, and if it was visible it is removed. If window-size is specified the data window is resized, or it was not visible it is made visible with the specified size. Example : WD 1 If no data window is present then a data window of one line is created. If the data window is currently on the screen, it is resized to one line. Enter/exit code window Syntax : EC Comments : The EC command toggles the cursor location between the code window and the command window. If the cursor was in the command window it is moved to the code window, and if the cursor was in the code window it is moved to the command window. When the cursor is in the code window several options become available that make debugging much easier. The options are: Point-and-shoot break points.Point-and-shoot break points are set with the BP command. If no parameters are specified with the BPX command an execution break point is set at the location of the cursor position in the code window. The cursor must be on a line that contains code (place the code window in mixed mode if you are unsure). The default function key assignment for BPX is F9. Go to cursor line.You can set a temporary break point at the cursor and go with the HERE command. The cursor must be on a line that contains code (place the code window in mixed mode if you are unsure). The default function key assignment for HERE is F7. Scrolling the code window.The code window can be scrolled only while the cursor is in the code window. The scrolling keys (UP arrow, DOWN arrow, PageUp and PageDown) are redefined while the cursor is in code window. When the cursor is in the code window the scrolling keys do the following: up Scroll code window up one line down Scroll code window down one pageup Scroll code window up one window pageDn Scroll code window down one window< Note : The code window must be visible for the EC command to work. Default Function Key: F6 Locate current instruction Syntax : . Comments : When the code window is visible, the . command makes the current source line or current instruction visible. 05.08 Debugger Customization Commands PAUSE Pause after each screen ALTKEY Set alternate key sequence to invoke Soft-ICE FKEY Show and edit function keys BASE Set/display current radix CTRL-P Toggle log session to printer Print-Screen Print contents of screen PRN Set printer output port Pause after each screen Syntax : PAUSE [ON | OFF] Comments : PAUSE controls screen pause at the end of each page. If PAUSE is ON, you are prompted to press any key before information is scrolled off the window. The prompt is displayed in the status line at the bottom of the window. If noparameter is specified, the current state of PAUSE is displayed. The default is PAUSE mode ON. Example : PAUSE ON This command specifies that subsequent window display commands will cause the screen to wait for you to press a key before scrolling new information off the window. Set alternate key sequence to invoke Soft-ICE Syntax : ALTKEY [ALTletter] | [CTRLletter] | [SYSREQ] Letter : Any letter (A - Z) Comments : The ALTKEY command allows the key sequence for popping up Soft-ICE to be changed. The key sequence be changed to CTRL + letter, ALT + letter, or the SysRq key. Occasionally you may be using a program that conflicts with the CTRL D key sequence that brings up the Soft-ICE window. One way to circumvent this possible problem is to use the ALTKEY command to change the key sequence. Another way is to add the SHIFT key to the current sequence. Soft-ICE does not respond to this key sequence and allows it to go through to your program. For example if a resident program you are using is brought up with the CTRL D key sequence, try using the key sequence CTRL SHIFT D to bring up your resident program. On some keyboards, you must press ALT and the prtsc key simultaneously to generate a system request. Care must be taken so the screen is not printed accidentally. If no parameter is specified, the current key sequence state is displayed. The default key sequence is CTRL D. Example : ALTKEY ALT Z This command specifies that the key sequence ALT Z will now be used to pop up the Soft-ICE window. Show and edit function keys Syntax : FKEY [function-key-name string] function-key-name : F1, F2... F12 string : The string consists of any valid Soft-ICE commands and the special character ^ (caret) and ; (semicolon). A ^ is placed in the string to make a command invisible. A ; is placed in the string to denote a carriage return. Comments : The FKEY command is used from the command line to assign a function key to a command string. Function key can be assigned to any command string that can be typed into Soft-ICE. If no parameters are specified, then the current function key assignments are displayed. To unassign a specified function key, use the FKEY command with these parameters: a function-key-name followed by a null string. The function keys can also be pre-initialized in the definition file S-ICE.DAT. For more information on function key definitions in the definition file, refer to section 6.4. Using carriage return symbols in a function key assignment string allows you to assign a function key a series of commands. A carriage return is represented by a ; (semicolon). If you put ^ (shift 6) in front of a function key definition, the subsequent command will be invisible. The command will function as normal, but all information displayed in the command window (including error messages) is suppressed. The invisible mode is useful when a command changes information in a window (code, register or data) but you do not want to clutter the command window, when a function key is made invisible with ^, the function key can be used in the middle of typing in other command without affecting their operation. For example, if you are using the default assignment for F2, you can toggle the register window with F2 even if you are partially through typing in your next command. Note : Soft-ICE now has a definition file named S-ICE.DAT. You can place function key assignments in this file so that function keys will be automatically assigned when Soft-ICE is loaded. The syntax for assigning a function key in the configuration file is: function-key-name = "string" When assigning function keys to a command string in S-ICE.DAT, the string must be enclosed in double quotes. Command line examples : FKEY F2 ^WR; This example will assign the toggle register window command to the F2 key. The ^ makes the function invisible, and the ; ends the function with a carriage return. The F2 key will toggle the register window on or off, and can even be evoked while typing in another command. FKEY F1 "G CS:120; R; G CS:" This example shows that multiple commands can be assigned to a single function key and that partial commands can be assigned for the user to complete. After this command is entered, pressing the F1 key will cause the program to execute until location CS:120 is reached, display the registers, then start the G command for the user to complete. FKEY F1 WD 3;D DS:100; This example will assign a series of commands to the F1 key. The function is visible, and ends with a carriage return. The F1 key will make the data window three lines long and dump data starting at DS:100. S-ICE.DAT example: F1 = "WR;WD 2;WC 10;" If this line is placed in S-ICE.DAT, when Soft-ICE is loaded it will assign the string to the F1 key. When F1 is pressed while in Soft-ICE, it will toggle the register window, create a data window of length 2 and a code window of length 10. For more information about assigning function key definitions in S-ICE.DAT, refer to chapter 6. Set/display current radix Syntax : BASE [10 | 16] Comments : The BASE command sets the current radix to base 10 or base 16. Base 10 is of limited use in the narrow window because of window width limitations. It also limits the amount of information displayed in some commands in the wide mode. When the current radix is base 10, all numbers and addresses typed into and displayed by Soft-ICE are in decimal, When the current radix is base 16, all numbers and addresses typed into Soft-ICE are in hexadecimal except for the source line numbers and the screen coordinates and sizes in the WIN command These exceptions are always typed in and displayed as decimal numbers. The default radix is base 16. Example : BASE 16 This example sets the current radix to base 16. Toggle log session to printer Syntax : CTRL-P Comments : When the CTRL key followed by the P key is pressed, all subsequent information displayed in the command window is also sent to the printer. To turn the log to printer mode off, type CTRL followed by P again. When you are sending a lot of information to the printer using CTRL-P, you may want to turn the PAUSE command OFF to allow information to scroll off the window without pressing a key. Print contents of screen Syntax : Print-Screen Comments : Depressing the print-screen key does a screen dump to printer. All information from the screen is sent the printer. If you wish to print the memory map or help information is usually much faster to use CTRL-P than Print-Screen. This is because Print-Screen prints every character on the screen including borders. Set printer output port Syntax : PRN [LPTx | COMx] x : a decimal number between 1 and 4. Comments : The PRN command allows you to send output from the CTRL-P and Print-Screen commands to a different printer port. If no parameters are supplied, PRN displays the currently assigned printer port. Example : PRN COM 1 This command causes the CTRL-P and Print-Screen command output to go to the COM 1 port. 05.09 Screen Control Commands FLASH Restore screen during P and T FLICK Screen flicker reduction WATCHV Set watch video mode RS Restore program screen CLS Clear window ALTSCR Change to alternate screen WIN Change size of Soft-ICE window Restore screen during P and T Syntax : FLASH [ON | OFF] Comments : The FLASH command lets you specify whether the screen will be restored during any Trace and Program step commands. If you specify that the screen is to be restored it is restored for the brief time period that the P or T command is executing. This feature is needed to debug sections of code that access video memory. If the P command executes across a call or an interrupt, the screen will always be restored, because the routine being called may write to the screen. If no parameter is specified, the current state of FLASH is displayed. The default is FLASH mode OFF. Example : FLASH ON This command turns on FLASH mode. The screen will be restored during any subsequent P or T commands. Screen flicker reduction Syntax : FLICK [ON | OFF] Comments : Certain types of video cards require waiting for horizontal or vertical retrace before outputting characters. If the video writes are made arbitrarily, flickering will appear while displaying characters. If flickering occurs on your screen while using the Soft-ICE window, you should turn FLICK on. With some EGA cards, colors will not be restored properly when you exit from Soft-ICE. This is a problem with virtualizing EGA video. The port 3DA is a video port used for two purposes. The first is old CGA software polling 3DA for hsync and vsync. This allows them to have flicker free output on some old CGA controller cards. The second is that it is used to reset a palette latch on EGA cards. Soft-ICE has an algorithm to avoid having to constantly watch this port, which would slow down old programs that think they are on a CGA. However, there can occasional be circumstances where this algorithm does not work. If you are using Soft- ICE on an EGA screen and you notice that the colors are not restored correctly, then turn FLICK ON and Soft-ICE will watch the 3DA port, fixing the problem. When FLICK mode is ON, screen update will be slower. If no parameter is specified, the current state of FLICK is displayed. The default is FLICK mode OFF. Example : FLICK ON This command turns on FLICK mode. This causes Soft-ICE to wait for the horizontal or vertical retrace before outputting characters. Set watch video mode Syntax : WATCHV [ON | OFF] Comments : The WATCHV command allows you to specify how Soft-ICE should watch the video ports. Normally, Soft-ICE only watches video ports after an INT 10 instruction has been executed that switches to a non-character video mode. Some programs do not use INT 10 to switch modes. In these cases, if WATCHV is OFF, Soft-ICE may have trouble saving and restoring the screen properly. Turning WATCHV ON will cause Soft-ICE to watch the video ports all the time. Turn WATCHV ON if you notice that Soft-ICE is not handling your screen properly, or if the cursor is not being restored properly. Turning WATCHV ON may have a performance impact in certain video modes. If no parameter is specified, the current state of WATCHV is displayed. The default is WATCHV mode OFF. Example : WATCHV ON This command turns on WATCHV mode. This causes Soft-ICE to watch additional video ports for the purpose of virtualization. Restore program screen Syntax : RS Comments : The RS command allows you to restore the program screen temporarily. The Soft-ICE window disappears until any key is pressed. This feature is useful when debugging graphic programs that update the screen frequently. When Soft-ICE is brought up, it returns to text mode. Using the RS command temporarily restores the graphics screen. Example : RS Clear window Syntax : CLS Comments : The CLS command clears the Soft-ICE window and moves the prompt and the cursor to the upper left-hand corner the window. Example : CLS Change to alternate screen Syntax : ALTSCR [ON | OFF] Comments : The ALTSCR command allows you to redirect the Soft-ICE output from your default screen to the alternate screen. This feature is useful, for instance, when you want to debug a graphics program without having to switch between the Soft-ICE window and the graphics display. ALTSCR requires the system to have two monitors attached. The alternate monitor should be in a character mode, which is the default mode for monitors. The default is ALTSCR mode OFF. Example : ALTSCR ON This command redirects screen output to the alternate monitor. Change size of Soft-ICE window Syntax : N : When N is specified, the window will be set to the narrow width : 46 characters. W : When W is specified, the window will be set to full screen width start-row : Number from 0 to 17 specifying row where window display starts. length : Number from 8 to 25 specifying how many lines tall you want the window to be. start-column : Column position of the left side of narrow window. The start-row and start-column specify the upper left hand corner of the narrow window. The start-column is ignored if applied to the wide window. Comments : The WIN command allows you to modify the width and height of the Soft-ICE display window. If no parameters are specified, this command toggles the window between wide and narrow screen display modes. If the WIN command is specified with only the N or the W parameter, the window size will be changed to the requested width at the current height. If the number of lines plus the starting row number is larger than25, the window length goes to the bottom of the screen. The default is WIN mode narrow. Examples : WIN N 4 9 30 This command causes the window display to start at row 4 and column 30, and to be 9 rows tall and 46 characters wide. WIN This command toggles the window display width from its current state (either wide or narrow) to the opposite state. WIN W 10 8 This command causes the window display to start at row 10, and to be 8 rows tall and go the width of the screen. 05.10 Symbol and Source Line Commands SYM Display/set symbol SYMLOC Relocate symbol base SRC Toggle between source, mixed and code FILE Change/display current source SS Search current source file for string Display/set symbol Syntax : SYM [symbol-name [value]] symbol-name : A valid symbol name. The symbol name can end with an * (asterisk). This allows searching if only the first part of the symbol name is known. The , (comma) character can be used as a wild card character in place of character in the symbol-name. value : This is a word value that is used if you want to set a symbol to a specific value. Comments : The SYM command allows displaying and setting of symbols. If SYM is entered with no parameters all symbols are displayed. The value of each symbol is displayed next to the symbol name. If a symbol name is specified with no value then the symbol name and value are displayed. If the symbol name was not found then nothing is displayed. The SYM command is often useful for finding a symbol name when you can only remember a portion of the name Two wild card methods are available for locating symbols. If symbol-name ends with an *, then all symbols that match the actual characters typed prior to the * will be displayed regardless of their ending characters. If a , is used in place of a specific character in symbol-name, that character is a wild card character. If value is specified, all symbols that match symbol-name are set to the value. All symbols have word values. Examples : SYM FOO* All symbols that start with FOO are displayed. SYM FOO* 6000 All symbols that start with FOO are given the value 6000. Relocate symbol base Syntax : SYMLOC segment-address Comments : The SYMLOC command relocates the segment components of all symbols relative to the specified segment address. This function is necessary when debugging loadable device drivers or other programs that can not be loaded directly with LDR.EXE. When relocating for a loadable device driver, use the value of the base address of the driver as found in the MAP command. When relocating for an .EXE program, the value is 10H greater than that found as the base in the MAP command. When relocating for a .COM program, use the base segment address that is found in the MAP command. The MAP command will display at least two entries for each program. The first is typically the environment and the second is typically the program. The base address of the program is the relocation value. Example : SYMLOC 1244 + 10 This will relocate all segments in the symbol table relative to 1244. The + 10 is used to relocate a TSR that was originally a .EXE file. If it is a .COM file the + 10 is not necessary. Toggle between source, mixed and code Syntax : SRC [?] Comments : The SRC command toggles between source mode, mixed mode and code mode in the code window. If SRC ? is entered, the current state is displayed. Example : SRC This command changes the current mode of the code window. If the mode was source, it becomes mixed. the mode was mixed, it becomes code. If the mode was code, it becomes source. Default-Function Key: F3 Change/display current source file Syntax : FILE [file-name] Comments : If a file-name is specified, that file becomes the current file and the start of the file is displayed in the code window. If no name is specified, the name of the current source file (if any) is displayed. The FILE command is often useful when setting a break point on a line that has no associated public symbol. Use file to bring the desired file into the code window, use the SS command to locate the specific line, move the cursor the specific line, then type BPX to set the break point. Note : Only source files that have been loaded into extended memory with LDR.EXE are available with the FILE command. Example : FILE MAIN.C If MAIN.C had been loaded with LDR.EXE, this command brings it up in the code window starting with line 1. Search current source file for string Syntax : SS [line-number] [' string'] Line-number : a decimal number String : a character string surrounded by quotes. The quotes can be either single quotes or double quotes. Comments : The SS command searches the current source file for the specified character string. If there is a match, the line that the string was located in will be displayed as the top line in the code window. The search starts at the specified line number. If no line number is specified the search starts at the top line displayed in the code window. If no parameters are specified, the search continues for the previously specified string. Note : The code window must be visible and in source mode before using the SS command. Example : SS 1 'if (i = = 3)' The current source file is searched starting at line 1 for the string 'if (i = = 3)'. The line containing the next occurrence of the string becomes the top line displayed in the code window.